home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 4 / Amiga Tools 4.iso / tools / internet-tools / connect-line / cl / devkit / docs / cllib.doc < prev    next >
Encoding:
Text File  |  1995-09-01  |  14.1 KB  |  613 lines
  1. TABLE OF CONTENTS
  2.  
  3. cl.lib/---history---
  4. cl.lib/---overview---
  5. cl.lib/--locale-support--
  6. cl.lib/--readargs-support--
  7. cl.lib/cl_addlog
  8. cl.lib/cl_alloc
  9. cl.lib/cl_allochook
  10. cl.lib/cl_allochooka4
  11. cl.lib/cl_allochooka4d
  12. cl.lib/cl_free
  13. cl.lib/cl_popdir
  14. cl.lib/cl_pushdir
  15. cl.lib/cl_setpri
  16. cl.lib/cl_setprwindowptr
  17. cl.lib/cl_strdup
  18. cl.lib/---history---                                     cl.lib/---history---
  19.  
  20.  8.4
  21.  ---
  22.  - locale support code insisted on "locale.library" to be openable.
  23.  
  24.  8.5
  25.  ---
  26.  - added ftzs.a code to avoid time() constantly opening ENV:TZ
  27.  
  28.  8.6
  29.  ---
  30.  - modified to open clutil V36
  31.  
  32.  8.7
  33.  ---
  34.  - added libinit for cl_route.library (CLRBase)
  35.  - locale support code cleaned up to use SetProgramDir() instead
  36.    of directly modifying pr_HomeDir
  37.  
  38.  8.8
  39.  ---
  40.  - added sasum.a code to speed up integer math operations.
  41.  
  42.  8.9
  43.  ---
  44.  - added replacement constructor for AslBase which opens
  45.    "asl.library" V38 instead of V37.
  46.  - added "__stack = 8192" define to be on the safe side
  47.    for MUI operations.
  48.  
  49.  8.10
  50.  ----
  51.  - replaced Connectline: with Prgdata: throughout
  52.  
  53.  8.11
  54.  ----
  55.  - replaced PRGDATA: with CONNECTLINE: throughout (ich find das nicht
  56.    zum Lachen ;-)
  57.  
  58.  8.12
  59.  ----
  60.  - modified to open clutil V38+
  61.  - added constructor/destructor for CLMidbBase (clmidb.library)
  62.  
  63.  8.13
  64.  ----
  65.  - CLMidbBase constructor was accidentally missing.
  66.  
  67.  9.0
  68.  ---
  69.  - cl_allochook() is no longer contained in the clalloc module.
  70.  - added cl_allochooka4()
  71.  
  72.  9.1
  73.  ---
  74.  - modified to open clutil V39+
  75.  
  76.  9.2
  77.  ---
  78.  - added constructor for "cl_mailmaster.library"
  79.  
  80.  9.3
  81.  ---
  82.  - modified to open clutil V40+
  83.  
  84.  9.4
  85.  ---
  86.  - added constructor for "clxfer.library"
  87.  
  88.  10.0
  89.  ----
  90.  - added cl_allocstrtab()
  91.  - modified to open clutil V41+
  92.  
  93.  10.1
  94.  ----
  95.  - removed sasum.a from lib
  96.  
  97.  10.2
  98.  ----
  99.  - modified cl_allochooka4() to not using "h_Data" for it's own purpose,
  100.    and to correctly pass a pointer to the hook itself in A0. New
  101.    function cl_allochooka4d() to set h_Data as well.
  102.  
  103.  10.3
  104.  ---
  105.  - modified to open clutil V42+
  106.  
  107.  10.4
  108.  ----
  109.  - added constructor for "cl_text.library"
  110.  
  111.  11.0
  112.  ----
  113.  - modified to open clutil V44+
  114.  - removed constructor for cllog.library
  115.  - added constructor for cl_log.library
  116.  - changed cl_addlog to use cl_log.library
  117.  
  118.  11.1
  119.  ----
  120.  - clsystem.library-Constructor now does CLS_LoadList()
  121.  - clboard.library-Constructor now does CLB_LoadList()
  122.  
  123.  11.2
  124.  ----
  125.  - changed CLMBase constructor to use cl_msg.library instead
  126.    of the now obsolete "cl_message.library"
  127.  - modified to open clutil V46+
  128.  
  129.  11.3
  130.  ----
  131.  - modified to open clutil V47+
  132.  
  133.  13.0
  134.  ----
  135.  - added constructor for cl_shell.library
  136.  
  137.  14.1
  138.  ----
  139.  - added __clctype-constructor (see cl/ctype.h)
  140.  
  141.  15.0
  142.  ----
  143.  - added constructor for cl_ansi.library
  144.  
  145. cl.lib/---overview---                                   cl.lib/---overview---
  146.  
  147.    "cl.lib" is a link library containing several support functions
  148.    for writing Connectline applications using SAS/C 6.51. Mainly,
  149.    it is the link interface for several services provided by
  150.    the "clutil.library" and other Connectline specific libs.
  151.  
  152.    It contains constructors/destructors for automatic opening
  153.    of all Connectline specific libraries, just like sc.lib contains
  154.    the same for the standard Amiga libraries.
  155.  
  156. cl.lib/--locale-support--                           cl.lib/--locale-support--
  157.  
  158.    "cl.lib" 3.0 Locale support
  159.  
  160.    Define the name of your program's catalog as
  161.    char *__clcatalogname = "prefs/system.catalog";
  162.    and dereference the given LocaleInfo structure.
  163.  
  164.    The constructor temporarly changes PROGDIR:
  165.    to point to CONNECTLINE: in order to allow
  166.    applications to be started from wherever the
  167.    user wants without worrying about the path.
  168.  
  169.    You may set
  170.    char *__clbuiltinlanguage = "...";
  171.    to change the builtin language name. Defaults
  172.    to "Deutsch".
  173.  
  174.  
  175. cl.lib/--readargs-support--                       cl.lib/--readargs-support--
  176.  
  177.    "cl.lib" 2.0 ReadArgs() template support functions
  178.  
  179.    Define your command template by setting
  180.    char **__clargstemplate = "<ReadArgs-Template>"
  181.    The args array will automagically be allocated by
  182.    the lib function.
  183.  
  184.    Setting "__clargshelp" to a non-NULL value enables
  185.    ReadArgs's extend help facility.
  186.  
  187.    A ReadArgs() error will cause your application to
  188.    terminate immediately, printing an errorcode consisting
  189.    of the CLI program name and the errorstring (via PrintFault())
  190.  
  191.    The ReadArgs() function is linked in by
  192.    referencing "__clargs" inside your code.
  193.  
  194.    New for V6: setting __clargsquiet to the integer index
  195.    of a switch item inside your args list causes your
  196.    process Input/Output handles to be replaced bei NIL:.
  197.    This is for easy implementation of QUIET/S-like
  198.    template options. Example: Template is "FILES/M,MULTI/S,QUIET/S",
  199.    so setting "long __clargsquiet = 2;" will cause the arg parser
  200.    to examine the QUIET switch of the args and then shut down any
  201.    Input/Output.
  202.  
  203. cl.lib/cl_addlog                                             cl.lib/cl_addlog
  204.  
  205.    NAME    
  206.    cl_addlog -- add entry to logfile (V7)
  207.    cl_addlogargs -- args pointer version of cl_addlog (V7)
  208.  
  209.    SYNOPSIS
  210.    cl_addlog( loglevel, fmtstring [,arg1...] )
  211.    cl_addlogargs( loglevel, fmtstring, argptr )
  212.  
  213.    void cl_addlog( LONG, STRPTR, ... );
  214.    void cl_addlogargs( LONG, STRPTR, APTR );
  215.  
  216.    FUNCTION
  217.    Add lines to log file with defined logID.
  218.  
  219.    INPUTS
  220.    loglevel -- log level of entry (not used until V11)
  221.    fmtstring -- standard printf()-like formating string
  222.    arg1 -- (optional) args
  223.  
  224.    RESULT
  225.    None.
  226.  
  227.    EXAMPLE
  228.  
  229.    NOTES
  230.    All outputs have a definied log ID which must be set by
  231.    declaring
  232.  
  233.     char *__cllogid = "LOGID";
  234.  
  235.    in your code.
  236.  
  237.    BUGS
  238.  
  239.    SEE ALSO
  240.  
  241. cl.lib/cl_alloc                                               cl.lib/cl_alloc
  242.  
  243.    NAME    
  244.    cl_alloc -- allocate from program's private pool (V2)
  245.  
  246.    SYNOPSIS
  247.    memblock = cl_alloc( size )
  248.  
  249.    void * cl_alloc( int );
  250.  
  251.    FUNCTION
  252.    Allocates some memory from the program's private
  253.    pool.
  254.  
  255.    INPUTS
  256.    size  -- size of block to allocate
  257.  
  258.    RESULT
  259.    memblock - Pointer to memory block, or NULL on error
  260.  
  261.    EXAMPLE
  262.  
  263.    NOTES
  264.    The cl.lib memory support functions consist of a constructor/destructor
  265.    pair which initializes and destroy an exec memory pool via clutil.library.
  266.    cl_alloc(), cl_free() and cl_strdup() work as their standard counterparts,
  267.    just via the pool. Every and all memory left ist automagically freed
  268.    upon program termination.
  269.  
  270.    You can modify the pool attributes with three longwords. Default defines
  271.    are also contained within "cl.lib", but may be overriden on your behalf.
  272.  
  273.    long __clpoolmemflags       Default: MEMF_CLEAR
  274.    long __clpoolpuddlesize    Default: 8192
  275.    long __clpooltresholdsize  Default: 4096
  276.  
  277.    These functions are not reentrant (unless linked with "cres.o")
  278.  
  279.    These functions are a just _very_ thin layer over "clutil.library"
  280.    and quite efficient.
  281.  
  282.    BUGS
  283.  
  284.    SEE ALSO
  285.    cl.lib/cl_free, cl.lib/cl_strdup, cl.lib/cl_allochook
  286.  
  287. cl.lib/cl_allochook                                       cl.lib/cl_allochook
  288.  
  289.    NAME    
  290.    cl_allochook -- allocate and fill out a hook structure (V4)
  291.  
  292.    SYNOPSIS
  293.    hook = cl_allochook( funcpointer, data )
  294.  
  295.    struct Hook * cl_allochook( HOOKFUNC, APTR );
  296.  
  297.    FUNCTION
  298.    Allocates and initializes a standard HOOK structure.
  299.  
  300.    INPUTS
  301.    funcpointer -- hook function (h_Entry)
  302.    data -- optional function data (h_Data)
  303.  
  304.    RESULT
  305.    hook -- Pointer to hook structure.
  306.  
  307.    EXAMPLE
  308.  
  309.    NOTES
  310.  
  311.    BUGS
  312.  
  313.    SEE ALSO
  314.    cl.lib/cl_free, cl.lib/cl_strdup, cl.lib/cl_alloc
  315.  
  316. cl.lib/cl_allochooka4                                   cl.lib/cl_allochooka4
  317.  
  318.    NAME    
  319.    cl_allochooka4 -- allocate and fill out a hook structure
  320.                      with automatic A4 saving (V9)
  321.  
  322.    SYNOPSIS
  323.    hook = cl_allochooka4( funcpointer )
  324.  
  325.    struct Hook * cl_allochooka4( HOOKFUNC );
  326.  
  327.    FUNCTION
  328.    Allocates and initializes a standard HOOK structure.
  329.    A4 will be saved in private date, and h_Entry will point to
  330.    a special function which saves and loads A4 upon
  331.    calling the real function. 
  332.  
  333.    INPUTS
  334.    funcpointer -- hook function. A4 will already be
  335.                   set up upon entry.
  336.  
  337.    RESULT
  338.    hook -- Pointer to hook structure.
  339.  
  340.    EXAMPLE
  341.  
  342.    NOTES
  343.    Using this function is more efficient than declaring your
  344.    hook function "__saveds" and it also works with resident
  345.    code generation.
  346.  
  347.    Until V10.2 of "cl.lib", this function modified A0 and used h_Data
  348.    for A4 storage.
  349.  
  350.    BUGS
  351.  
  352.    SEE ALSO
  353.    cl.lib/cl_free, cl.lib/cl_strdup, cl.lib/cl_allochook
  354.  
  355. cl.lib/cl_allochooka4d                                 cl.lib/cl_allochooka4d
  356.  
  357.    NAME    
  358.    cl_allochooka4d -- allocate and fill out a hook structure
  359.                      with automatic A4 saving and h_Data setup (V10)
  360.  
  361.    SYNOPSIS
  362.    hook = cl_allochooka4d( funcpointer, data )
  363.  
  364.    struct Hook * cl_allochooka4d( HOOKFUNC, APTR );
  365.  
  366.    FUNCTION
  367.    Allocates and initializes a standard HOOK structure.
  368.    A4 will be saved in private date, and h_Entry will point to
  369.    a special function which saves and loads A4 upon
  370.    calling the real function. 
  371.  
  372.    INPUTS
  373.    funcpointer -- hook function. A4 will already be
  374.                   set up upon entry.
  375.    data -- your custom data.
  376.  
  377.    RESULT
  378.    hook -- Pointer to hook structure.
  379.  
  380.    EXAMPLE
  381.  
  382.    NOTES
  383.    Using this function is more efficient than declaring your
  384.    hook function "__saveds" and it also works with resident
  385.    code generation.
  386.  
  387.    Until V10.2 of "cl.lib", this function modified A0 and used h_Data
  388.    for A4 storage.
  389.  
  390.    BUGS
  391.  
  392.    SEE ALSO
  393.    cl.lib/cl_free, cl.lib/cl_strdup, cl.lib/cl_allochook, cl.lib/cl_allochook
  394. a4
  395.  
  396. cl.lib/cl_free                                                 cl.lib/cl_free
  397.  
  398.    NAME    
  399.    cl_free -- free memory allocated from program's private pool.
  400.  
  401.    SYNOPSIS
  402.    cl_free( memblock )
  403.  
  404.    void cl_free( void * );
  405.  
  406.    FUNCTION
  407.    Frees memory previously allocated by a call to cl_alloc(),
  408.    cl_strdup() or cl_allochook().
  409.  
  410.    INPUTS
  411.    memblock -- block to be freeed.
  412.  
  413.    RESULT
  414.    None.
  415.  
  416.    EXAMPLE
  417.  
  418.    NOTES
  419.    The cl.lib memory support functions consist of a constructor/destructor
  420.    pair which initializes and destroy an exec memory pool via clutil.library.
  421.    cl_alloc(), cl_free() and cl_strdup() work as their standard counterparts,
  422.    just via the pool. Every and all memory left ist automagically freed
  423.    upon program termination.
  424.  
  425.    You can modify the pool attributes with three longwords. Default defines
  426.    are also contained within "cl.lib", but may be overriden on your behalf.
  427.  
  428.    long __clpoolmemflags       Default: MEMF_CLEAR
  429.    long __clpoolpuddlesize    Default: 8192
  430.    long __clpooltresholdsize  Default: 4096
  431.  
  432.    These functions are not reentrant (unless linked with "cres.o")
  433.  
  434.    These functions are a just _very_ thin layer over "clutil.library"
  435.    and quite efficient.
  436.  
  437.    BUGS
  438.  
  439.    SEE ALSO
  440.    cl.lib/cl_alloc, cl.lib/cl_strdup, cl.lib/cl_allochook
  441.  
  442. cl.lib/cl_popdir                                             cl.lib/cl_popdir
  443.  
  444.    NAME    
  445.    cl_popdir -- pop directory saved with cl_pushdir() (V8)
  446.  
  447.    SYNOPSIS
  448.    cl_popdir()
  449.  
  450.    void cl_popdir( void );
  451.  
  452.    FUNCTION
  453.    Pop directory from directory stack.
  454.  
  455.    INPUTS
  456.    None.
  457.  
  458.    RESULT
  459.    None.
  460.  
  461.    EXAMPLE
  462.  
  463.    NOTES
  464.  
  465.    BUGS
  466.  
  467.    SEE ALSO
  468.    cl.lib/cl_pushdir()
  469.  
  470. cl.lib/cl_pushdir                                           cl.lib/cl_pushdir
  471.  
  472.    NAME    
  473.    cl_pushdir -- change current directory and keep previous
  474.                  on directory stack (V8)
  475.  
  476.    SYNOPSIS
  477.    success = cl_pushdir( dirname )
  478.  
  479.    BOOL cl_pushdir( STRPTR );
  480.  
  481.    FUNCTION
  482.    Change current directory and keep the previous
  483.    current dir on a special directory stack to
  484.    allow popping via cl_popdir().
  485.  
  486.    INPUTS
  487.    dirname -- name of directory to change to.
  488.  
  489.    RESULT
  490.    success -- TRUE or FALSE
  491.  
  492.    EXAMPLE
  493.  
  494.    NOTES
  495.  
  496.    BUGS
  497.  
  498.    SEE ALSO
  499.    cl.lib/cl_popdir()
  500.  
  501. cl.lib/cl_setpri                                             cl.lib/cl_setpri
  502.  
  503.    NAME    
  504.    cl_setpri -- set task priority (V5)
  505.  
  506.    SYNOPSIS
  507.    cl_setpri( taskpri )
  508.  
  509.    void cl_setpri( int );
  510.  
  511.    FUNCTION
  512.    Set your own process' priority.
  513.  
  514.    INPUTS
  515.    taskpri -- new task priority
  516.  
  517.    RESULT
  518.    None.
  519.  
  520.    EXAMPLE
  521.  
  522.    NOTES
  523.    Calling this function will result in linking in a constructor/
  524.    destructor pair that saves the original task priority and
  525.    restores it upon exit.
  526.  
  527.    This function may be called multiple times within a
  528.    program.
  529.  
  530.    BUGS
  531.  
  532.    SEE ALSO
  533.  
  534. cl.lib/cl_setprwindowptr                             cl.lib/cl_setprwindowptr
  535.  
  536.    NAME    
  537.    cl_setprwindowptr -- set process' pr_WindowPtr (V5)
  538.  
  539.    SYNOPSIS
  540.    cl_setprwindowptr( window )
  541.  
  542.    void cl_setprwindowptr( struct Window * );
  543.  
  544.    FUNCTION
  545.    Set your own process' pr_WindowPtr.
  546.  
  547.    INPUTS
  548.    window -- new pr_WindowPtr or PRWINDOWPTR_QUIET (-1)
  549.  
  550.    RESULT
  551.    None.
  552.  
  553.    EXAMPLE
  554.  
  555.    NOTES
  556.    Calling this function will result in linking in a constructor/
  557.    destructor pair that saves the original pr_WindowPtr and
  558.    restores it upon exit.
  559.  
  560.    This function may be called multiple times within a
  561.    program.
  562.  
  563.    BUGS
  564.  
  565.    SEE ALSO
  566.  
  567. cl.lib/cl_strdup                                             cl.lib/cl_strdup
  568.  
  569.    NAME    
  570.    cl_strdup -- duplicate string via cl_alloc (V2)
  571.  
  572.    SYNOPSIS
  573.    newstring = cl_strdup( string )
  574.  
  575.    STRPTR cl_alloc( StRPTR );
  576.  
  577.    FUNCTION
  578.    Allocates memory of size strlen( string ) + 1 and copies
  579.    the string contents.
  580.  
  581.    INPUTS
  582.    string -- string to duplicate
  583.  
  584.    RESULT
  585.    newstring -- duplicated string or NULL upon error
  586.  
  587.    EXAMPLE
  588.  
  589.    NOTES
  590.    The cl.lib memory support functions consist of a constructor/destructor
  591.    pair which initializes and destroy an exec memory pool via clutil.library.
  592.    cl_alloc(), cl_free() and cl_strdup() work as their standard counterparts,
  593.    just via the pool. Every and all memory left ist automagically freed
  594.    upon program termination.
  595.  
  596.    You can modify the pool attributes with three longwords. Default defines
  597.    are also contained within "cl.lib", but may be overriden on your behalf.
  598.  
  599.    long __clpoolmemflags       Default: MEMF_CLEAR
  600.    long __clpoolpuddlesize    Default: 8192
  601.    long __clpooltresholdsize  Default: 4096
  602.  
  603.    These functions are not reentrant (unless linked with "cres.o")
  604.  
  605.    These functions are a just _very_ thin layer over "clutil.library"
  606.    and quite efficient.
  607.  
  608.    BUGS
  609.  
  610.    SEE ALSO
  611.    cl.lib/cl_free, cl.lib/cl_alloc, cl.lib/cl_allochook
  612.  
  613.